<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
    <link href="../Styles/style.css" rel="stylesheet" type="text/css"/>


</head>

<body>
<div class="article-body">
    <div class="article-body">

        <div class="article-intro">

            <h1>Java 文档注释
            </h1>
            <p>
                Java 支持三种注释方式。前两种分别是 <strong>//</strong> 和 <strong>/* */</strong>，第三种被称作说明注释，它以 <strong>/**</strong> 开始，以 <strong>*/</strong>结束。</p><p>
            说明注释允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息，并输出到HTML文件中。</p><p>
            说明注释，使你更加方便的记录你的程序信息。</p><hr>
            <h2>
                javadoc 标签</h2>
            <p>
                javadoc 工具软件识别以下标签：
            </p>
            <table class="reference">
                <tbody>
                <tr>
                    <th>
                        <strong>标签</strong></th>
                    <th style="text-align: center;">
                        <strong>描述</strong></th>
                    <th style="text-align: center;">
                        <strong>示例</strong></th>
                </tr>
                <tr>
                    <td>
                        @author</td>
                    <td>
                        标识一个类的作者</td>
                    <td>
                        @author description</td>
                </tr>
                <tr>
                    <td>
                        @deprecated</td>
                    <td>
                        指名一个过期的类或成员</td>
                    <td>
                        @deprecated description</td>
                </tr>
                <tr>
                    <td>
                        {@docRoot}</td>
                    <td>
                        指明当前文档根目录的路径</td>
                    <td>
                        Directory Path</td>
                </tr>
                <tr>
                    <td>
                        @exception</td>
                    <td>
                        标志一个类抛出的异常</td>
                    <td>
                        @exception exception-name explanation</td>
                </tr>
                <tr>
                    <td>
                        {@inheritDoc}</td>
                    <td>
                        从直接父类继承的注释</td>
                    <td>
                        Inherits a comment from the immediate surperclass.</td>
                </tr>
                <tr>
                    <td>
                        {@link}</td>
                    <td>
                        插入一个到另一个主题的链接</td>
                    <td>
                        {@link name text}</td>
                </tr>
                <tr>
                    <td>
                        {@linkplain}</td>
                    <td>
                        插入一个到另一个主题的链接，但是该链接显示纯文本字体</td>
                    <td>
                        Inserts an in-line link to another topic.</td>
                </tr>
                <tr>
                    <td>
                        @param</td>
                    <td>
                        说明一个方法的参数</td>
                    <td>
                        @param parameter-name explanation</td>
                </tr>
                <tr>
                    <td>
                        @return</td>
                    <td>
                        说明返回值类型</td>
                    <td>
                        @return explanation</td>
                </tr>
                <tr>
                    <td>
                        @see</td>
                    <td>
                        指定一个到另一个主题的链接</td>
                    <td>
                        @see anchor</td>
                </tr>
                <tr>
                    <td>
                        @serial</td>
                    <td>
                        说明一个序列化属性</td>
                    <td>
                        @serial description</td>
                </tr>
                <tr>
                    <td>
                        @serialData</td>
                    <td>
                        说明通过writeObject( ) 和&nbsp;writeExternal( )方法写的数据</td>
                    <td>
                        @serialData description</td>
                </tr>
                <tr>
                    <td>
                        @serialField</td>
                    <td>
                        说明一个ObjectStreamField组件</td>
                    <td>
                        @serialField name type description</td>
                </tr>
                <tr>
                    <td>
                        @since</td>
                    <td>
                        标记当引入一个特定的变化时</td>
                    <td>
                        @since release</td>
                </tr>
                <tr>
                    <td>
                        @throws</td>
                    <td>
                        和 @exception标签一样.</td>
                    <td>
                        The @throws tag has the same meaning as the @exception tag.</td>
                </tr>
                <tr>
                    <td>
                        {@value}</td>
                    <td>
                        显示常量的值，该常量必须是static属性。</td>
                    <td>
                        Displays the value of a constant, which must be a static field.</td>
                </tr>
                <tr>
                    <td>
                        @version</td>
                    <td>
                        指定类的版本</td>
                    <td>
                        @version info</td>
                </tr>
                </tbody>
            </table>
            <hr><h2>文档注释</h2>
            <p>
                在开始的 <strong>/**</strong> 之后，第一行或几行是关于类、变量和方法的主要描述。</p><p>
            之后，你可以包含一个或多个何种各样的 <strong>@</strong> 标签。每一个 <strong>@</strong> 标签必须在一个新行的开始或者在一行的开始紧跟星号(*).</p><p>
            多个相同类型的标签应该放成一组。例如，如果你有三个 <strong>@see</strong> 标签，可以将它们一个接一个的放在一起。</p><p>
            下面是一个类的说明注释的实例：</p>
            <div class="example">
                <div class="example_code">
                    <pre class="hl-main"><span class="hl-comment">/*</span><span class="hl-comment">** 这个类绘制一个条形图
*</span><span class="hl-inlinedoc"> @author </span><span class="hl-comment">runoob
*</span><span class="hl-inlinedoc"> @version </span><span class="hl-comment">1.2
</span><span class="hl-comment">*/</span></pre>
                </div>
            </div>
            <hr><h2>
            javadoc 输出什么</h2>
            <p>

                javadoc 工具将你 Java 程序的源代码作为输入，输出一些包含你程序注释的HTML文件。</p><p>
            每一个类的信息将在独自的HTML文件里。javadoc 也可以输出继承的树形结构和索引。</p><p>
            由于 javadoc 的实现不同，工作也可能不同，你需要检查你的 Java 开发系统的版本等细节，选择合适的 Javadoc 版本。</p>
            <h3>
                实例</h3>
            <p>
                下面是一个使用说明注释的简单实例。注意每一个注释都在它描述的项目的前面。</p><p>
            在经过 javadoc 处理之后，SquareNum 类的注释将在 SquareNum.html 中找到。</p>
            <div class="example">
                <h2 class="example">SquareNum.java 文件代码：</h2>
                <div class="example_code">
                    <pre class="hl-main"><span class="hl-reserved">import</span><span class="hl-code"> </span><span class="hl-identifier">java</span><span class="hl-code">.</span><span class="hl-identifier">io</span><span class="hl-code">.*;

</span><span class="hl-comment">/*</span><span class="hl-comment">*
* 这个类演示了文档注释
*</span><span class="hl-inlinedoc"> @author </span><span class="hl-comment">Ayan Amhed
*</span><span class="hl-inlinedoc"> @version </span><span class="hl-comment">1.2
</span><span class="hl-comment">*/</span><span class="hl-code">
</span><span class="hl-reserved">public</span><span class="hl-code"> </span><span class="hl-reserved">class</span><span class="hl-code"> </span><span class="hl-identifier">SquareNum</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
   </span><span class="hl-comment">/*</span><span class="hl-comment">*
   * This method returns the square of num.
   * This is a multiline description. You can use
   * as many lines as you like.
   *</span><span class="hl-inlinedoc"> @param </span><span class="hl-comment">num The value to be squared.
   *</span><span class="hl-inlinedoc"> @return </span><span class="hl-comment">num squared.
   </span><span class="hl-comment">*/</span><span class="hl-code">
   </span><span class="hl-reserved">public</span><span class="hl-code"> </span><span class="hl-types">double</span><span class="hl-code"> </span><span class="hl-identifier">square</span><span class="hl-brackets">(</span><span class="hl-types">double</span><span class="hl-code"> </span><span class="hl-identifier">num</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
      </span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-identifier">num</span><span class="hl-code"> * </span><span class="hl-identifier">num</span><span class="hl-code">;
   </span><span class="hl-brackets">}</span><span class="hl-code">
   </span><span class="hl-comment">/*</span><span class="hl-comment">*
   * This method inputs a number from the user.
   *</span><span class="hl-inlinedoc"> @return </span><span class="hl-comment">The value input as a double.
   *</span><span class="hl-inlinedoc"> @exception </span><span class="hl-comment">IOException On input error.
   *</span><span class="hl-inlinedoc"> @see </span><span class="hl-comment">IOException
   </span><span class="hl-comment">*/</span><span class="hl-code">
   </span><span class="hl-reserved">public</span><span class="hl-code"> </span><span class="hl-types">double</span><span class="hl-code"> </span><span class="hl-identifier">getNumber</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-reserved">throws</span><span class="hl-code"> </span><span class="hl-identifier">IOException</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
      </span><span class="hl-identifier">InputStreamReader</span><span class="hl-code"> </span><span class="hl-identifier">isr</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">InputStreamReader</span><span class="hl-brackets">(</span><span class="hl-identifier">System</span><span class="hl-code">.</span><span class="hl-identifier">in</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-identifier">BufferedReader</span><span class="hl-code"> </span><span class="hl-identifier">inData</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">BufferedReader</span><span class="hl-brackets">(</span><span class="hl-identifier">isr</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-identifier">String</span><span class="hl-code"> </span><span class="hl-identifier">str</span><span class="hl-code">;
      </span><span class="hl-identifier">str</span><span class="hl-code"> = </span><span class="hl-identifier">inData</span><span class="hl-code">.</span><span class="hl-identifier">readLine</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Double</span><span class="hl-brackets">(</span><span class="hl-identifier">str</span><span class="hl-brackets">)</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-identifier">doubleValue</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
   </span><span class="hl-brackets">}</span><span class="hl-code">
   </span><span class="hl-comment">/*</span><span class="hl-comment">*
   * This method demonstrates square().
   *</span><span class="hl-inlinedoc"> @param </span><span class="hl-comment">args Unused.
   *</span><span class="hl-inlinedoc"> @return </span><span class="hl-comment">Nothing.
   *</span><span class="hl-inlinedoc"> @exception </span><span class="hl-comment">IOException On input error.
   *</span><span class="hl-inlinedoc"> @see </span><span class="hl-comment">IOException
   </span><span class="hl-comment">*/</span><span class="hl-code">
   </span><span class="hl-reserved">public</span><span class="hl-code"> </span><span class="hl-types">static</span><span class="hl-code"> </span><span class="hl-types">void</span><span class="hl-code"> </span><span class="hl-identifier">main</span><span class="hl-brackets">(</span><span class="hl-identifier">String</span><span class="hl-code"> </span><span class="hl-identifier">args</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-reserved">throws</span><span class="hl-code"> </span><span class="hl-identifier">IOException</span><span class="hl-code">
   </span><span class="hl-brackets">{</span><span class="hl-code">
      </span><span class="hl-identifier">SquareNum</span><span class="hl-code"> </span><span class="hl-identifier">ob</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">SquareNum</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-types">double</span><span class="hl-code"> </span><span class="hl-identifier">val</span><span class="hl-code">;
      </span><span class="hl-identifier">System</span><span class="hl-code">.</span><span class="hl-identifier">out</span><span class="hl-code">.</span><span class="hl-identifier">println</span><span class="hl-brackets">(</span><span class="hl-quotes">"</span><span class="hl-string">Enter value to be squared: </span><span class="hl-quotes">"</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-identifier">val</span><span class="hl-code"> = </span><span class="hl-identifier">ob</span><span class="hl-code">.</span><span class="hl-identifier">getNumber</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-identifier">val</span><span class="hl-code"> = </span><span class="hl-identifier">ob</span><span class="hl-code">.</span><span class="hl-identifier">square</span><span class="hl-brackets">(</span><span class="hl-identifier">val</span><span class="hl-brackets">)</span><span class="hl-code">;
      </span><span class="hl-identifier">System</span><span class="hl-code">.</span><span class="hl-identifier">out</span><span class="hl-code">.</span><span class="hl-identifier">println</span><span class="hl-brackets">(</span><span class="hl-quotes">"</span><span class="hl-string">Squared value is </span><span class="hl-quotes">"</span><span class="hl-code"> + </span><span class="hl-identifier">val</span><span class="hl-brackets">)</span><span class="hl-code">;
   </span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-brackets">}</span></pre>
                </div>
            </div>
            <p>
                如下，使用 javadoc 工具处理 SquareNum.java 文件：
            </p>
            <pre class="prettyprint prettyprinted" style=""><span class="pln">$ javadoc </span><span class="typ">SquareNum</span><span class="pun">.</span><span class="pln">java
</span><span class="typ">Loading</span><span class="pln"> source file </span><span class="typ">SquareNum</span><span class="pun">.</span><span class="pln">java</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Constructing</span><span class="pln"> </span><span class="typ">Javadoc</span><span class="pln"> information</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Standard</span><span class="pln"> </span><span class="typ">Doclet</span><span class="pln"> version </span><span class="lit">1.5</span><span class="pun">.</span><span class="lit">0_13</span><span class="pln">
</span><span class="typ">Building</span><span class="pln"> tree </span><span class="kwd">for</span><span class="pln"> all the packages </span><span class="kwd">and</span><span class="pln"> classes</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> </span><span class="typ">SquareNum</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">SquareNum</span><span class="pun">.</span><span class="pln">java</span><span class="pun">:</span><span class="lit">39</span><span class="pun">:</span><span class="pln"> warning </span><span class="pun">-</span><span class="pln"> </span><span class="lit">@return</span><span class="pln"> tag cannot be used\
                      </span><span class="kwd">in</span><span class="pln"> method </span><span class="kwd">with</span><span class="pln"> </span><span class="kwd">void</span><span class="pln"> </span><span class="kwd">return</span><span class="pln"> type</span><span class="pun">.</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> </span><span class="kwd">package</span><span class="pun">-</span><span class="pln">frame</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> </span><span class="kwd">package</span><span class="pun">-</span><span class="pln">summary</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> </span><span class="kwd">package</span><span class="pun">-</span><span class="pln">tree</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> constant</span><span class="pun">-</span><span class="pln">values</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Building</span><span class="pln"> index </span><span class="kwd">for</span><span class="pln"> all the packages </span><span class="kwd">and</span><span class="pln"> classes</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> overview</span><span class="pun">-</span><span class="pln">tree</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> index</span><span class="pun">-</span><span class="pln">all</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> deprecated</span><span class="pun">-</span><span class="pln">list</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Building</span><span class="pln"> index </span><span class="kwd">for</span><span class="pln"> all classes</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> allclasses</span><span class="pun">-</span><span class="pln">frame</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> allclasses</span><span class="pun">-</span><span class="pln">noframe</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> index</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> help</span><span class="pun">-</span><span class="pln">doc</span><span class="pun">.</span><span class="pln">html</span><span class="pun">...</span><span class="pln">
</span><span class="typ">Generating</span><span class="pln"> stylesheet</span><span class="pun">.</span><span class="pln">css</span><span class="pun">...</span><span class="pln">
</span><span class="lit">1</span><span class="pln"> warning
$</span></pre>


        </div>

    </div>
</div>

</body>
</html>
